home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 April: Mac OS SDK / Dev.CD Apr 97 SDK1.toast / Development Kits (Disc 1) / Apple Game Sprockets / NetSprocket 1.0.3 / NetSprocket.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-12-12  |  13.7 KB  |  577 lines  |  [TEXT/CWIE]
  1. /*
  2.  *    File:            NetSprocket.h
  3.  *
  4.  *    Version:        Apple Game Sprockets, NetSprocket 1.0.2
  5.  *
  6.  *    Dependencies:    Universal Interfaces 2.1.2 on ETO #20
  7.  *                    Open Transport interfaces 1.1
  8.  *
  9.  *    Contents:        Public interfaces for NetSprocket.
  10.  *
  11.  *    Bugs:            If you find a problem with this file or NetSprocketLib,
  12.  *                    please send e-mail describing the problem in enough detail
  13.  *                    to be reproduced, and include the version number above, the
  14.  *                    version of MacOS and hardware configuration information to
  15.  *                    sprockets@adr.apple.com.
  16.  *
  17.  *    Copyright (c) 1996 Apple Computer, Inc.  All rights reserved.
  18.  */
  19.  
  20. #ifndef __NETSPROCKET__
  21. #define __NETSPROCKET__
  22.  
  23. #ifndef __TYPES__
  24. #include <Types.h>
  25. #endif
  26.  
  27. #ifndef __EVENTS__
  28. #include <Events.h>
  29. #endif
  30.  
  31. #ifndef __OPENTRANSPORT__
  32. #include <OpenTransport.h>
  33. #endif
  34.  
  35. #ifndef __OPENTPTINTERNET__
  36. #include <OpenTptInternet.h>
  37. #endif
  38.  
  39. #if PRAGMA_ALIGN_SUPPORTED
  40. #pragma options align=power
  41. #endif
  42.  
  43. #if PRAGMA_IMPORT_SUPPORTED
  44. #pragma import on
  45. #endif
  46.  
  47. #define kNSpMaxPlayerNameLen        31
  48. #define kNSpMaxGroupNameLen            31
  49. #define kNSpMaxPasswordLen            31
  50. #define kNSpMaxGameNameLen            31
  51. #define kNSpMaxDefinitionStringLen    255
  52.  
  53.  
  54. /* NetSprocket basic types */
  55. typedef    struct NSpGamePrivate        *NSpGameReference;
  56. typedef    struct NSpProtocolPrivate    *NSpProtocolReference;
  57. typedef    struct NSpListPrivate        *NSpProtocolListReference;
  58. typedef struct NSPAddressPrivate    *NSpAddressReference;
  59. typedef SInt32                        NSpEventCode;
  60. typedef    SInt32                        NSpGameID;
  61. typedef    SInt32                        NSpPlayerID;
  62. typedef NSpPlayerID                    NSpGroupID;
  63. typedef UInt32                        NSpPlayerType;
  64. typedef SInt32                        NSpFlags;
  65.  
  66. /* Individual player info */
  67. typedef struct NSpPlayerInfo
  68. {
  69.     NSpPlayerID        id;
  70.     NSpPlayerType    type;
  71.     Str31            name;
  72.     UInt32            groupCount;
  73.     NSpGroupID        groups[kVariableLengthArray];
  74. } NSpPlayerInfo, *NSpPlayerInfoPtr;
  75.  
  76.     
  77. /* list of all players */
  78. typedef struct NSpPlayerEnumeration
  79. {
  80.     UInt32                count;
  81.     NSpPlayerInfoPtr    playerInfo[kVariableLengthArray];
  82. } NSpPlayerEnumeration, *NSpPlayerEnumerationPtr;
  83.  
  84.  
  85. /* Individual group info */
  86. typedef struct NSpGroupInfo
  87. {
  88.     NSpGroupID    id;
  89.     UInt32        playerCount;
  90.     NSpPlayerID    players[kVariableLengthArray];
  91. } NSpGroupInfo, *NSpGroupInfoPtr;
  92.  
  93.  
  94. /* List of all groups */
  95. typedef struct NSpGroupEnumeration
  96. {
  97.     UInt32            count;
  98.     NSpGroupInfoPtr    groups[kVariableLengthArray];
  99. } NSpGroupEnumeration, *NSpGroupEnumerationPtr;
  100.  
  101. /* Topology types */
  102. typedef UInt32 NSpTopology;
  103. enum
  104. {
  105.     kNSpClientServer =     0x00000001
  106. };
  107.  
  108. /* Game information */
  109. typedef struct NSpGameInfo
  110. {
  111.     UInt32        maxPlayers;
  112.     UInt32        currentPlayers;
  113.     UInt32        currentGroups;
  114.     NSpTopology    topology;
  115.     UInt32        reserved;
  116.     Str31        name;
  117.     Str31        password;
  118. } NSpGameInfo;
  119.     
  120.     
  121. /* Structure used for sending and receiving network messages */
  122. typedef struct NSpMessageHeader
  123. {
  124.     UInt32        version;    /* Used by NetSprocket.  Don't touch this */
  125.     SInt32        what;        /* The kind of message (e.g. player joined) */
  126.     NSpPlayerID    from;        /* ID of the sender */
  127.     NSpPlayerID    to;            /* (player or group) id of the intended recipient */
  128.     UInt32        id;            /* Unique ID for this message & (from) player */
  129.     UInt32        when;        /* Timestamp for the message */
  130.     UInt32        messageLen;    /* Bytes of data in the entire message (including the header) */
  131. } NSpMessageHeader;
  132.  
  133.  
  134. /* NetSprocket-defined message structures */
  135.  
  136. typedef struct NSpErrorMessage
  137. {
  138.     NSpMessageHeader    header;
  139.     OSStatus            error;
  140. } NSpErrorMessage;
  141.  
  142.  
  143. typedef struct NSpJoinRequestMessage
  144. {
  145.     NSpMessageHeader    header;
  146.     Str31                name;
  147.     Str31                password;
  148.     UInt32                type;
  149.     UInt32                customDataLen;
  150.     UInt8                customData[kVariableLengthArray];
  151. } NSpJoinRequestMessage;
  152.  
  153.  
  154. typedef struct NSpJoinApprovedMessage
  155. {
  156.     NSpMessageHeader    header;
  157. } NSpJoinApprovedMessage;
  158.  
  159.  
  160. typedef struct NSpJoinDeniedMessage
  161. {
  162.     NSpMessageHeader    header;
  163.     Str255                reason;
  164. } NSpJoinDeniedMessage;
  165.  
  166.  
  167. typedef struct NSpPlayerJoinedMessage
  168. {
  169.     NSpMessageHeader    header;
  170.     UInt32                playerCount;
  171.     NSpPlayerInfo            playerInfo;    
  172. } NSpPlayerJoinedMessage;
  173.  
  174.  
  175. typedef struct NSpPlayerLeftMessage
  176. {
  177.     NSpMessageHeader    header;
  178.     UInt32                playerCount;
  179.     NSpPlayerID            playerID;    
  180. } NSpPlayerLeftMessage;
  181.  
  182. typedef struct NSpHostChangedMessage
  183. {
  184.     NSpMessageHeader    header;
  185.     NSpPlayerID            newHost;
  186. } NSpHostChangedMessage;
  187.  
  188.  
  189. typedef struct NSpGameTerminatedMessage
  190. {
  191.     NSpMessageHeader    header;
  192. } NSpGameTerminatedMessage;
  193.  
  194.  
  195. /* Different kinds of messages.  These can NOT be bitwise ORed together */
  196. enum
  197. {
  198.     kNSpSendFlag_Junk =         0x00100000,        /* will be sent (try once) when there is nothing else pending */
  199.     kNSpSendFlag_Normal =         0x00200000,        /* will be sent immediately (try once) */
  200.     kNSpSendFlag_Registered =     0x00400000        /* will be sent immediately (guaranteed, in order) */
  201. };
  202.  
  203.  
  204. /* Options for message delivery.  These can be bitwise ORed together with each other,
  205.         as well as with ONE of the above */
  206. enum 
  207. {
  208.     kNSpSendFlag_FailIfPipeFull =     0x00000001,
  209.     kNSpSendFlag_SelfSend =         0x00000002,
  210.     kNSpSendFlag_Blocking =         0x00000004
  211. };
  212.  
  213.  
  214. /* Options for Hosting Joining, and Deleting games */
  215. enum
  216. {
  217.     kNSpGameFlag_DontAdvertise            =    0x00000001,
  218.     kNSpGameFlag_ForceTerminateGame     =     0x00000002
  219. };
  220.  
  221. /* Message "what" types */
  222. /* Apple reserves all negative "what" values (anything with bit 32 set) */ 
  223. enum 
  224. {
  225.     kNSpSystemMessagePrefix = 0x80000000,
  226.     kNSpError =                 kNSpSystemMessagePrefix | 0x7FFFFFFF,
  227.     kNSpJoinRequest =         kNSpSystemMessagePrefix | 0x00000001,
  228.     kNSpJoinApproved =         kNSpSystemMessagePrefix | 0x00000002,
  229.     kNSpJoinDenied =         kNSpSystemMessagePrefix | 0x00000003,
  230.     kNSpPlayerJoined =         kNSpSystemMessagePrefix | 0x00000004,
  231.     kNSpPlayerLeft =         kNSpSystemMessagePrefix | 0x00000005,
  232.     kNSpHostChanged =         kNSpSystemMessagePrefix | 0x00000006,
  233.     kNSpGameTerminated=     kNSpSystemMessagePrefix | 0x00000007
  234. };
  235.  
  236.  
  237. /* Special TPlayerIDs  for sending messages */
  238. enum
  239. {
  240.     kNSpAllPlayers =     0x00000000,
  241.     kNSpHostOnly =        0xFFFFFFFF
  242. };
  243.     
  244. #ifdef __cplusplus
  245. extern "C" {
  246. #endif
  247.  
  248. /************************  Initialization  ************************/
  249.  
  250. OSStatus NSpInitialize(
  251.     UInt32                         inStandardMessageSize, 
  252.     UInt32                         inBufferSize, 
  253.     UInt32                         inQElements, 
  254.     NSpGameID                     inGameID, 
  255.     UInt32                         inTimeout);
  256.  
  257.  
  258. /**************************  Protocols  **************************/
  259.  
  260. /* Programmatic protocol routines */
  261. OSStatus NSpProtocol_New(
  262.     const char*                 inDefinitionString, 
  263.     NSpProtocolReference*        outReference);
  264.  
  265. void NSpProtocol_Dispose(
  266.     NSpProtocolReference         inProtocolRef);
  267.  
  268. OSStatus NSpProtocol_ExtractDefinitionString(
  269.     NSpProtocolReference         inProtocolRef, 
  270.     char*                        outDefinitionString);
  271.  
  272.  
  273. /* Protocol list routines */
  274. OSStatus NSpProtocolList_New(
  275.     NSpProtocolReference         inProtocolRef,
  276.     NSpProtocolListReference*    outList);
  277.  
  278. void NSpProtocolList_Dispose(
  279.     NSpProtocolListReference     inProtocolList);
  280.  
  281. OSStatus NSpProtocolList_Append(
  282.     NSpProtocolListReference     inProtocolList,
  283.     NSpProtocolReference         inProtocolRef);
  284.  
  285. OSStatus NSpProtocolList_Remove(
  286.     NSpProtocolListReference     inProtocolList, 
  287.     NSpProtocolReference         inProtocolRef);
  288.  
  289. OSStatus NSpProtocolList_RemoveIndexed(
  290.     NSpProtocolListReference     inProtocolList,
  291.     UInt32                         inIndex);
  292.  
  293. UInt32 NSpProtocolList_GetCount(
  294.     NSpProtocolListReference     inProtocolList);
  295.  
  296. NSpProtocolReference NSpProtocolList_GetIndexedRef(
  297.     NSpProtocolListReference     inProtocolList,
  298.     UInt32                         inIndex);
  299.  
  300.  
  301. /* Helpers */
  302. NSpProtocolReference NSpProtocol_CreateAppleTalk(
  303.     ConstStr31Param             inNBPName,
  304.     ConstStr31Param             inNBPType, 
  305.     UInt32                         inMaxRTT,
  306.     UInt32                         inMinThruput);
  307.  
  308. NSpProtocolReference NSpProtocol_CreateIP(
  309.     InetPort                     inPort,
  310.     UInt32                         inMaxRTT,
  311.     UInt32                         inMinThruput);
  312.  
  313.  
  314. /***********************  Human Interface  ************************/
  315. typedef pascal Boolean (*NSpEventProcPtr) (EventRecord* inEvent);
  316.  
  317.  
  318. NSpAddressReference NSpDoModalJoinDialog(
  319.     ConstStr31Param             inGameType, 
  320.     ConstStr255Param             inEntityListLabel,
  321.     Str31                         ioName, 
  322.     Str31                         ioPassword, 
  323.     NSpEventProcPtr             inEventProcPtr);
  324.  
  325. Boolean NSpDoModalHostDialog(
  326.     NSpProtocolListReference     ioProtocolList, 
  327.     Str31                         ioGameName, 
  328.     Str31                         ioPlayerName,
  329.     Str31                         ioPassword, 
  330.     NSpEventProcPtr             inEventProcPtr);
  331.  
  332.  
  333. /*********************  Hosting and Joining  **********************/
  334.  
  335. OSStatus NSpGame_Host(
  336.     NSpGameReference*            outGame, 
  337.     NSpProtocolListReference     inProtocolList, 
  338.     UInt32                         inMaxPlayers, 
  339.     ConstStr31Param             inGameName, 
  340.     ConstStr31Param             inPassword,
  341.     ConstStr31Param             inPlayerName, 
  342.     NSpPlayerType                 inPlayerType, 
  343.     NSpTopology                 inTopology,
  344.     NSpFlags                     inFlags);
  345.  
  346. OSStatus NSpGame_Join(
  347.     NSpGameReference*            outGame, 
  348.     NSpAddressReference         inAddress, 
  349.     ConstStr31Param             inName,
  350.     ConstStr31Param             inPassword,
  351.     NSpPlayerType                 inType, 
  352.     void*                        inCustomData,
  353.     UInt32                         inCustomDataLen,  
  354.     NSpFlags                     inFlags);
  355.  
  356. OSStatus NSpGame_EnableAdvertising(
  357.     NSpGameReference             inGame, 
  358.     NSpProtocolReference         inProtocol, 
  359.     Boolean                     inEnable);
  360.  
  361. OSStatus NSpGame_Dispose(
  362.     NSpGameReference             inGame, 
  363.     NSpFlags                     inFlags);
  364.  
  365. OSStatus NSpGame_GetInfo(
  366.     NSpGameReference             inGame,
  367.     NSpGameInfo                  *ioInfo);
  368.  
  369. /**************************  Messaging  **************************/
  370.  
  371. OSStatus NSpMessage_Send(
  372.     NSpGameReference             inGame, 
  373.     NSpMessageHeader*            inMessage, 
  374.     NSpFlags                     inFlags);
  375.  
  376. NSpMessageHeader *NSpMessage_Get(
  377.     NSpGameReference             inGame);
  378.  
  379. void NSpMessage_Release(
  380.     NSpGameReference             inGame, 
  381.     NSpMessageHeader*            inMessage);
  382.  
  383. /* Helpers */
  384. OSStatus NSpMessage_SendTo(
  385.     NSpGameReference             inGame,
  386.     NSpPlayerID                    inTo,
  387.     SInt32                        inWhat, 
  388.     void*                        inData,
  389.     UInt32                        inDataLen, 
  390.     NSpFlags                     inFlags);
  391.     
  392.  
  393. /*********************  Player Information  **********************/
  394.  
  395. NSpPlayerID NSpPlayer_GetMyID(
  396.     NSpGameReference             inGame);
  397.  
  398. OSStatus NSpPlayer_GetInfo(
  399.     NSpGameReference             inGame, 
  400.     NSpPlayerID                 inPlayerID, 
  401.     NSpPlayerInfoPtr*            outInfo);
  402.  
  403. void NSpPlayer_ReleaseInfo(
  404.     NSpGameReference             inGame, 
  405.     NSpPlayerInfoPtr             inInfo);
  406.  
  407. OSStatus NSpPlayer_GetEnumeration(
  408.     NSpGameReference             inGame, 
  409.     NSpPlayerEnumerationPtr*    outPlayers);
  410.  
  411. void NSpPlayer_ReleaseEnumeration(
  412.     NSpGameReference             inGame, 
  413.     NSpPlayerEnumerationPtr     inPlayers);
  414.  
  415. UInt32 NSpPlayer_GetRoundTripTime(
  416.     NSpGameReference             inGame, 
  417.     NSpPlayerID                 inPlayer); 
  418.  
  419. UInt32 NSpPlayer_GetThruput(
  420.     NSpGameReference             inGame, 
  421.     NSpPlayerID                 inPlayer); 
  422.  
  423.  
  424. /*********************  Group Management  **********************/
  425.  
  426. OSStatus NSpGroup_New(
  427.     NSpGameReference             inGame, 
  428.     NSpGroupID*                    outGroupID);
  429.  
  430. OSStatus NSpGroup_Dispose(
  431.     NSpGameReference             inGame, 
  432.     NSpGroupID                     inGroupID);
  433.  
  434. OSStatus NSpGroup_AddPlayer(
  435.     NSpGameReference             inGame, 
  436.     NSpGroupID                     inGroupID, 
  437.     NSpPlayerID                 inPlayerID);
  438.  
  439. OSStatus NSpGroup_RemovePlayer(
  440.     NSpGameReference             inGame, 
  441.     NSpGroupID                     inGroupID,
  442.     NSpPlayerID                 inPlayerID);
  443.  
  444. OSStatus NSpGroup_GetInfo(
  445.     NSpGameReference             inGame, 
  446.     NSpGroupID                     inGroupID, 
  447.     NSpGroupInfoPtr*            outInfo);
  448.  
  449. void NSpGroup_ReleaseInfo(
  450.     NSpGameReference             inGame, 
  451.     NSpGroupInfoPtr             inInfo);
  452.  
  453. OSStatus NSpGroup_GetEnumeration(
  454.     NSpGameReference             inGame, 
  455.     NSpGroupEnumerationPtr*        outGroups);
  456.  
  457. void NSpGroup_ReleaseEnumeration(
  458.     NSpGameReference             inGame, 
  459.     NSpGroupEnumerationPtr         inGroups);
  460.  
  461.  
  462. /**************************  Utilities  ***************************/
  463.  
  464. NumVersion NSpGetVersion(void);
  465.  
  466. void NSpClearMessageHeader(
  467.     NSpMessageHeader*            inMessage);
  468.  
  469. UInt32 NSpGetCurrentTimeStamp(
  470.     NSpGameReference             inGame);
  471.  
  472. NSpAddressReference    NSpConvertOTAddrToAddressReference(
  473.     OTAddress*                    inAddress);
  474.  
  475. OTAddress *NSpConvertAddressReferenceToOTAddr(
  476.     NSpAddressReference         inAddress);
  477.  
  478. void NSpReleaseAddressReference(
  479.     NSpAddressReference         inAddress);
  480.  
  481.  
  482. /************************ Advanced/Async routines ****************/
  483.  
  484. typedef pascal void (*NSpCallbackProcPtr)(
  485.     NSpGameReference             inGame, 
  486.     void*                         inContext, 
  487.     NSpEventCode                 inCode, 
  488.     OSStatus                     inStatus, 
  489.     void*                         inCookie);
  490.  
  491. OSStatus NSpInstallCallbackHandler(
  492.     NSpCallbackProcPtr             inHandler, 
  493.     void*                        inContext);
  494.  
  495.  
  496. typedef pascal Boolean (*NSpJoinRequestHandlerProcPtr)(
  497.     NSpGameReference             inGame, 
  498.     NSpJoinRequestMessage*        inMessage, 
  499.     void*                         inContext,
  500.     Str255                        outReason);
  501.  
  502. OSStatus NSpInstallJoinRequestHandler(
  503.     NSpJoinRequestHandlerProcPtr inHandler, 
  504.     void*                        inContext);
  505.  
  506.  
  507. typedef pascal Boolean (*NSpMessageHandlerProcPtr)(
  508.     NSpGameReference             inGame, 
  509.     NSpMessageHeader*            inMessage, 
  510.     void*                         inContext);
  511.  
  512. OSStatus NSpInstallAsyncMessageHandler(
  513.     NSpMessageHandlerProcPtr     inHandler, 
  514.     void*                        inContext);
  515.  
  516.  
  517.  
  518.  
  519. #ifdef __cplusplus
  520. }
  521. #endif
  522.  
  523. #ifdef __CFM68K__
  524. #pragma import reset
  525. #endif
  526.  
  527. /* NetSprocket Error Codes */
  528. enum
  529. {
  530.     kNSpInitializationFailedErr         = -30360,
  531.     kNSpAlreadyInitializedErr             = -30361,
  532.     kNSpTopologyNotSupportedErr         = -30362,
  533.     kNSpPipeFullErr                         = -30364,
  534.     kNSpHostFailedErr                     = -30365,
  535.     kNSpProtocolNotAvailableErr         = -30366,
  536.     kNSpInvalidGameRefErr                 = -30367,
  537.     kNSpInvalidParameterErr             = -30369,
  538.     kNSpOTNotPresentErr                 = -30370,
  539.     kNSpOTVersionTooOldErr                = -30371,
  540.     kNSpMemAllocationErr                 = -30373,
  541.     kNSpAlreadyAdvertisingErr             = -30374,
  542.     kNSpNotAdvertisingErr                 = -30376,
  543.     kNSpInvalidAddressErr                 = -30377,
  544.     kNSpFreeQExhaustedErr                = -30378,
  545.     kNSpRemovePlayerFailedErr            = -30379,
  546.     kNSpAddressInUseErr                    = -30380,
  547.     kNSpFeatureNotImplementedErr        = -30381,
  548.     kNSpNameRequiredErr                 = -30382,
  549.     kNSpInvalidPlayerIDErr                 = -30383,
  550.     kNSpInvalidGroupIDErr                 = -30384,
  551.     kNSpNoPlayersErr                     = -30385,
  552.     kNSpNoGroupsErr                     = -30386,
  553.     kNSpNoHostVolunteersErr             = -30387,
  554.     kNSpCreateGroupFailedErr             = -30388,
  555.     kNSpAddPlayerFailedErr                 = -30389,
  556.     kNSpInvalidDefinitionErr            = -30390,
  557.     kNSpInvalidProtocolRefErr            = -30391,
  558.     kNSpInvalidProtocolListErr            = -30392,
  559.     kNSpTimeoutErr                        = -30393,
  560.     kNSpGameTerminatedErr                = -30394,
  561.     kNSpConnectFailedErr                = -30395,
  562.     kNSpSendFailedErr                    = -30396,
  563.     kNSpJoinFailedErr                    = -30399
  564. };
  565.  
  566.  
  567.  
  568. #if PRAGMA_IMPORT_SUPPORTED
  569. #pragma import off
  570. #endif
  571.  
  572. #if PRAGMA_ALIGN_SUPPORTED
  573. #pragma options align=reset
  574. #endif
  575.  
  576. #endif /* __NETSPROCKET__ */
  577.